

<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
  <meta charset="utf-8">
  
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  
  <title>BetterCAP stable documentation</title>
  

  
  
    <link rel="shortcut icon" href="/legacy/assets/favicon.png"/>
  
  
  

  

  
  
    

  

  
  
    <link rel="stylesheet" href="/legacy/assets/css/theme.css" type="text/css" />
  

  

  
        <link rel="index" title="Index"
              href="genindex.html"/>
        <link rel="search" title="Search" href="search.html"/>
    <link rel="top" title="None" href="index.html#document-index"/> 

  
  <script src="/legacy/assets/js/modernizr.min.js"></script>

</head>

<body class="wy-body-for-nav" role="document">

   
  <div class="wy-grid-for-nav">

    
    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
      <div class="wy-side-scroll">
        <div class="wy-side-nav-search">
          
    

          
            <a href="index.html#document-index">
          

          
            
            <img src="/legacy/assets/logo.png" class="logo" />
          
          </a>

          
            
            
              <div class="version">
                stable
              </div>
            
          

          

          

        </div>

        <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
          
            
            
            
              <!-- Local TOC -->
              <div class="local-toc"><ul>
<li class="toctree-l1"><a class="reference internal" href="index.html#document-intro">Introduction</a></li>
<li class="toctree-l1"><a class="reference internal" href="index.html#document-install">Installation</a></li>
<li class="toctree-l1"><a class="reference internal" href="index.html#document-contribute">Contributing</a></li>
</ul>
<p class="caption"><span class="caption-text">Main Features</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="index.html#document-main">General Options</a><ul>
<li class="toctree-l2"><a class="reference internal" href="index.html#examples">Examples</a></li>
<li class="toctree-l2"><a class="reference internal" href="index.html#options">Options</a><ul>
<li class="toctree-l3"><a class="reference internal" href="index.html#i-interface-iface"><code class="docutils literal"><span class="pre">-I,</span> <span class="pre">--interface</span> <span class="pre">IFACE</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="index.html#use-mac-address"><code class="docutils literal"><span class="pre">--use-mac</span> <span class="pre">ADDRESS</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="index.html#random-mac"><code class="docutils literal"><span class="pre">--random-mac</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="index.html#g-gateway-address"><code class="docutils literal"><span class="pre">-G,</span> <span class="pre">--gateway</span> <span class="pre">ADDRESS</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="index.html#t-target-address1-address2"><code class="docutils literal"><span class="pre">-T,</span> <span class="pre">--target</span> <span class="pre">ADDRESS1,ADDRESS2</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="index.html#ignore-address1-address2"><code class="docutils literal"><span class="pre">--ignore</span> <span class="pre">ADDRESS1,ADDRESS2</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="index.html#no-discovery"><code class="docutils literal"><span class="pre">--no-discovery</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="index.html#no-target-nbns"><code class="docutils literal"><span class="pre">--no-target-nbns</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="index.html#packet-throttle-number"><code class="docutils literal"><span class="pre">--packet-throttle</span> <span class="pre">NUMBER</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="index.html#check-updates"><code class="docutils literal"><span class="pre">--check-updates</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="index.html#h-help"><code class="docutils literal"><span class="pre">-h,</span> <span class="pre">--help</span></code></a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="index.html#document-logging">Logging</a><ul>
<li class="toctree-l2"><a class="reference internal" href="index.html#examples">Examples</a></li>
<li class="toctree-l2"><a class="reference internal" href="index.html#options">Options</a><ul>
<li class="toctree-l3"><a class="reference internal" href="index.html#o-log-log-file"><code class="docutils literal"><span class="pre">-O,</span> <span class="pre">--log</span> <span class="pre">LOG_FILE</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="index.html#log-timestamp"><code class="docutils literal"><span class="pre">--log-timestamp</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="index.html#d-debug"><code class="docutils literal"><span class="pre">-D,</span> <span class="pre">--debug</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="index.html#silent"><code class="docutils literal"><span class="pre">--silent</span></code></a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="index.html#document-spoofing">Spoofing</a><ul>
<li class="toctree-l2"><a class="reference internal" href="index.html#examples">Examples</a></li>
<li class="toctree-l2"><a class="reference internal" href="index.html#options">Options</a><ul>
<li class="toctree-l3"><a class="reference internal" href="index.html#s-spoofer-name"><code class="docutils literal"><span class="pre">-S,</span> <span class="pre">--spoofer</span> <span class="pre">NAME</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="index.html#no-spoofing"><code class="docutils literal"><span class="pre">--no-spoofing</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="index.html#kill"><code class="docutils literal"><span class="pre">--kill</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="index.html#full-duplex"><code class="docutils literal"><span class="pre">--full-duplex</span></code></a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="index.html#document-sniffing">Sniffing &amp; Credentials Harvesting</a><ul>
<li class="toctree-l2"><a class="reference internal" href="index.html#examples">Examples</a></li>
<li class="toctree-l2"><a class="reference internal" href="index.html#options">Options</a><ul>
<li class="toctree-l3"><a class="reference internal" href="index.html#x-sniffer"><code class="docutils literal"><span class="pre">-X,</span> <span class="pre">--sniffer</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="index.html#l-local"><code class="docutils literal"><span class="pre">-L,</span> <span class="pre">--local</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="index.html#sniffer-source-file"><code class="docutils literal"><span class="pre">--sniffer-source</span> <span class="pre">FILE</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="index.html#sniffer-output-file"><code class="docutils literal"><span class="pre">--sniffer-output</span> <span class="pre">FILE</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="index.html#sniffer-filter-expression"><code class="docutils literal"><span class="pre">--sniffer-filter</span> <span class="pre">EXPRESSION</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="index.html#p-parsers-parsers"><code class="docutils literal"><span class="pre">-P,</span> <span class="pre">--parsers</span> <span class="pre">PARSERS</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="index.html#custom-parser-expression"><code class="docutils literal"><span class="pre">--custom-parser</span> <span class="pre">EXPRESSION</span></code></a></li>
</ul>
</li>
</ul>
</li>
</ul>
<p class="caption"><span class="caption-text">Proxying &amp; Modules</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="index.html#document-proxying">About Proxying</a></li>
<li class="toctree-l1"><a class="reference internal" href="index.html#document-proxying/http">HTTP/HTTPS</a><ul>
<li class="toctree-l2"><a class="reference internal" href="index.html#sample-module">Sample Module</a></li>
<li class="toctree-l2"><a class="reference internal" href="index.html#http">HTTP</a><ul>
<li class="toctree-l3"><a class="reference internal" href="index.html#ssl-stripping">SSL Stripping</a></li>
<li class="toctree-l3"><a class="reference internal" href="index.html#hsts-bypass">HSTS Bypass</a></li>
<li class="toctree-l3"><a class="reference internal" href="index.html#demonstration">Demonstration</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="index.html#https">HTTPS</a><ul>
<li class="toctree-l3"><a class="reference internal" href="index.html#server-name-indication">Server Name Indication</a></li>
<li class="toctree-l3"><a class="reference internal" href="index.html#installing-certification-authority">Installing Certification Authority</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="index.html#options">Options</a><ul>
<li class="toctree-l3"><a class="reference internal" href="index.html#proxy-upstream-address-address"><code class="docutils literal"><span class="pre">--proxy-upstream-address</span> <span class="pre">ADDRESS</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="index.html#allow-local-connections"><code class="docutils literal"><span class="pre">--allow-local-connections</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="index.html#proxy"><code class="docutils literal"><span class="pre">--proxy</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="index.html#proxy-port-port"><code class="docutils literal"><span class="pre">--proxy-port</span> <span class="pre">PORT</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="index.html#no-sslstrip"><code class="docutils literal"><span class="pre">--no-sslstrip</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="index.html#log-http-response"><code class="docutils literal"><span class="pre">--log-http-response</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="index.html#proxy-module-module"><code class="docutils literal"><span class="pre">--proxy-module</span> <span class="pre">MODULE</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="index.html#http-ports-port1-port2"><code class="docutils literal"><span class="pre">--http-ports</span> <span class="pre">PORT1,PORT2</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="index.html#proxy-https"><code class="docutils literal"><span class="pre">--proxy-https</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="index.html#proxy-https-port-port"><code class="docutils literal"><span class="pre">--proxy-https-port</span> <span class="pre">PORT</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="index.html#proxy-pem-file"><code class="docutils literal"><span class="pre">--proxy-pem</span> <span class="pre">FILE</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="index.html#https-ports-port1-port2"><code class="docutils literal"><span class="pre">--https-ports</span> <span class="pre">PORT1,PORT2</span></code></a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="index.html#document-proxying/tcp">TCP</a><ul>
<li class="toctree-l2"><a class="reference internal" href="index.html#sample-module">Sample Module</a></li>
<li class="toctree-l2"><a class="reference internal" href="index.html#options">Options</a><ul>
<li class="toctree-l3"><a class="reference internal" href="index.html#tcp-proxy"><code class="docutils literal"><span class="pre">--tcp-proxy</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="index.html#tcp-proxy-module-module"><code class="docutils literal"><span class="pre">--tcp-proxy-module</span> <span class="pre">MODULE</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="index.html#tcp-proxy-port-port"><code class="docutils literal"><span class="pre">--tcp-proxy-port</span> <span class="pre">PORT</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="index.html#tcp-proxy-upstream-address-address"><code class="docutils literal"><span class="pre">--tcp-proxy-upstream-address</span> <span class="pre">ADDRESS</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="index.html#tcp-proxy-upstream-port-port"><code class="docutils literal"><span class="pre">--tcp-proxy-upstream-port</span> <span class="pre">PORT</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="index.html#tcp-proxy-upstream-address-port"><code class="docutils literal"><span class="pre">--tcp-proxy-upstream</span> <span class="pre">ADDRESS:PORT</span></code></a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="index.html#document-proxying/udp">UDP</a><ul>
<li class="toctree-l2"><a class="reference internal" href="index.html#sample-module">Sample Module</a></li>
<li class="toctree-l2"><a class="reference internal" href="index.html#options">Options</a><ul>
<li class="toctree-l3"><a class="reference internal" href="index.html#udp-proxy"><code class="docutils literal"><span class="pre">--udp-proxy</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="index.html#udp-proxy-module-module"><code class="docutils literal"><span class="pre">--udp-proxy-module</span> <span class="pre">MODULE</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="index.html#udp-proxy-port-port"><code class="docutils literal"><span class="pre">--udp-proxy-port</span> <span class="pre">PORT</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="index.html#udp-proxy-upstream-address-address"><code class="docutils literal"><span class="pre">--udp-proxy-upstream-address</span> <span class="pre">ADDRESS</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="index.html#udp-proxy-upstream-port-port"><code class="docutils literal"><span class="pre">--udp-proxy-upstream-port</span> <span class="pre">PORT</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="index.html#udp-proxy-upstream-address-port"><code class="docutils literal"><span class="pre">--udp-proxy-upstream</span> <span class="pre">ADDRESS:PORT</span></code></a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="index.html#document-proxying/custom">Third Party Proxies</a><ul>
<li class="toctree-l2"><a class="reference internal" href="index.html#custom-proxy-address"><code class="docutils literal"><span class="pre">--custom-proxy</span> <span class="pre">ADDRESS</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="index.html#custom-proxy-port-port"><code class="docutils literal"><span class="pre">--custom-proxy-port</span> <span class="pre">PORT</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="index.html#custom-https-proxy-address"><code class="docutils literal"><span class="pre">--custom-https-proxy</span> <span class="pre">ADDRESS</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="index.html#custom-https-proxy-port-port"><code class="docutils literal"><span class="pre">--custom-https-proxy-port</span> <span class="pre">PORT</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="index.html#custom-redirection-rule"><code class="docutils literal"><span class="pre">--custom-redirection</span> <span class="pre">RULE</span></code></a></li>
</ul>
</li>
</ul>
<p class="caption"><span class="caption-text">Builtin Servers</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="index.html#document-servers/http">HTTP</a><ul>
<li class="toctree-l2"><a class="reference internal" href="index.html#httpd"><code class="docutils literal"><span class="pre">--httpd</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="index.html#httpd-port-port"><code class="docutils literal"><span class="pre">--httpd-port</span> <span class="pre">PORT</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="index.html#httpd-path-path"><code class="docutils literal"><span class="pre">--httpd-path</span> <span class="pre">PATH</span></code></a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="index.html#document-servers/dns">DNS</a><ul>
<li class="toctree-l2"><a class="reference internal" href="index.html#dns-file"><code class="docutils literal"><span class="pre">--dns</span> <span class="pre">FILE</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="index.html#dns-port-port"><code class="docutils literal"><span class="pre">--dns-port</span> <span class="pre">PORT</span></code></a></li>
</ul>
</li>
</ul>
</div>
            
          
        </div>
      </div>
    </nav>

    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">

      
      <nav class="wy-nav-top" role="navigation" aria-label="top navigation">
        
          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
          <a href="index.html#document-index">BetterCAP</a>
        
      </nav>


      
      <div class="wy-nav-content">
        <div class="rst-content">
          















<div role="navigation" aria-label="breadcrumbs navigation">

  <ul class="wy-breadcrumbs">
    
      <li><a href="index.html#document-index">Docs</a> &raquo;</li>
        
      <li>BetterCAP stable documentation</li>
    
    
      <li class="wy-breadcrumbs-aside">
        
            
        
      </li>
    
  </ul>

  
  <hr/>
</div>
          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
           <div itemprop="articleBody">
            
  <div class="section" id="documentation">
<h1>Documentation<a class="headerlink" href="#documentation" title="Permalink to this headline">¶</a></h1>
<p>BetterCAP is a powerful, flexible and portable tool created to perform various types of <strong>MITM</strong> attacks against a network, manipulate <strong>HTTP</strong>, <strong>HTTPS</strong> and <strong>TCP</strong> traffic in realtime, sniff for credentials and much more.</p>
<iframe width="100%" height="400" src="https://www.youtube.com/embed/BfvoONHXuQA" frameborder="0" allowfullscreen></iframe><br/><br/><p>Check on the <strong>Next</strong> button below and start hacking!</p>
<div class="toctree-wrapper compound">
<span id="document-intro"></span><div class="section" id="introduction">
<span id="introduction"></span><h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
<p>BetterCAP is a powerful, flexible and portable tool created to perform various types of <strong>MITM</strong> attacks against a network, manipulate <strong>HTTP</strong>, <strong>HTTPS</strong> and <strong>TCP</strong> traffic in realtime, sniff for credentials and much more.</p>
<div class="section" id="you-are-the-man-in-the-middle">
<span id="you-are-the-man-in-the-middle"></span><h3>You Are the Man in the Middle<a class="headerlink" href="#you-are-the-man-in-the-middle" title="Permalink to this headline">¶</a></h3>
<p>What is a <strong>MITM</strong> ( <em>Man In The Middle</em> ) attack? Let's ask <a class="reference external" href="https://en.wikipedia.org/wiki/Man-in-the-middle_attack">Wikipedia</a>!</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">In</span> <span class="n">cryptography</span> <span class="ow">and</span> <span class="n">computer</span> <span class="n">security</span><span class="p">,</span> <span class="n">a</span> <span class="n">man</span><span class="o">-</span><span class="ow">in</span><span class="o">-</span><span class="n">the</span><span class="o">-</span><span class="n">middle</span> <span class="n">attack</span> <span class="p">(</span><span class="n">often</span> <span class="n">abbreviated</span> <span class="n">to</span> <span class="n">MITM</span><span class="p">,</span> <span class="n">MitM</span><span class="p">,</span> <span class="n">MIM</span><span class="p">,</span> <span class="n">MiM</span> <span class="n">attack</span> <span class="ow">or</span> <span class="n">MITMA</span><span class="p">)</span> <span class="ow">is</span> <span class="n">an</span> <span class="n">attack</span> <span class="n">where</span> <span class="n">the</span> <span class="n">attacker</span> <span class="n">secretly</span> <span class="n">relays</span> <span class="ow">and</span> <span class="n">possibly</span> <span class="n">alters</span> <span class="n">the</span> <span class="n">communication</span> <span class="n">between</span> <span class="n">two</span> <span class="n">parties</span> <span class="n">who</span> <span class="n">believe</span> <span class="n">they</span> <span class="n">are</span> <span class="n">directly</span> <span class="n">communicating</span> <span class="k">with</span> <span class="n">each</span> <span class="n">other</span><span class="o">.</span> <span class="n">Man</span><span class="o">-</span><span class="ow">in</span><span class="o">-</span><span class="n">the</span><span class="o">-</span><span class="n">middle</span> <span class="n">attacks</span> <span class="n">can</span> <span class="n">be</span> <span class="n">thought</span> <span class="n">about</span> <span class="n">through</span> <span class="n">a</span> <span class="n">chess</span> <span class="n">analogy</span><span class="o">.</span>
<span class="n">Mallory</span><span class="p">,</span> <span class="n">who</span> <span class="n">barely</span> <span class="n">knows</span> <span class="n">how</span> <span class="n">to</span> <span class="n">play</span> <span class="n">chess</span><span class="p">,</span> <span class="n">claims</span> <span class="n">that</span> <span class="n">she</span> <span class="n">can</span> <span class="n">play</span> <span class="n">two</span> <span class="n">grandmasters</span> <span class="n">simultaneously</span> <span class="ow">and</span> <span class="n">either</span> <span class="n">win</span> <span class="n">one</span> <span class="n">game</span> <span class="ow">or</span> <span class="n">draw</span> <span class="n">both</span><span class="o">.</span> <span class="n">She</span> <span class="n">waits</span> <span class="k">for</span> <span class="n">the</span> <span class="n">first</span> <span class="n">grandmaster</span> <span class="n">to</span> <span class="n">make</span> <span class="n">a</span> <span class="n">move</span> <span class="ow">and</span> <span class="n">then</span> <span class="n">makes</span> <span class="n">this</span> <span class="n">same</span> <span class="n">move</span> <span class="n">against</span> <span class="n">the</span> <span class="n">second</span> <span class="n">grandmaster</span><span class="o">.</span> <span class="n">When</span> <span class="n">the</span> <span class="n">second</span> <span class="n">grandmaster</span> <span class="n">responds</span><span class="p">,</span> <span class="n">Mallory</span> <span class="n">makes</span> <span class="n">the</span> <span class="n">same</span> <span class="n">play</span> <span class="n">against</span> <span class="n">the</span> <span class="n">first</span><span class="o">.</span> <span class="n">She</span> <span class="n">plays</span> <span class="n">the</span> <span class="n">entire</span> <span class="n">game</span> <span class="n">this</span> <span class="n">way</span> <span class="ow">and</span> <span class="n">cannot</span> <span class="n">lose</span><span class="o">.</span>
<span class="n">A</span> <span class="n">man</span><span class="o">-</span><span class="ow">in</span><span class="o">-</span><span class="n">the</span><span class="o">-</span><span class="n">middle</span> <span class="n">attack</span> <span class="ow">is</span> <span class="n">a</span> <span class="n">similar</span> <span class="n">strategy</span> <span class="ow">and</span> <span class="n">can</span> <span class="n">be</span> <span class="n">used</span> <span class="n">against</span> <span class="n">many</span> <span class="n">cryptographic</span> <span class="n">protocols</span><span class="o">.</span> <span class="n">One</span> <span class="n">example</span> <span class="n">of</span> <span class="n">man</span><span class="o">-</span><span class="ow">in</span><span class="o">-</span><span class="n">the</span><span class="o">-</span><span class="n">middle</span> <span class="n">attacks</span> <span class="ow">is</span> <span class="n">active</span> <span class="n">eavesdropping</span><span class="p">,</span> <span class="ow">in</span> <span class="n">which</span> <span class="n">the</span> <span class="n">attacker</span> <span class="n">makes</span> <span class="n">independent</span> <span class="n">connections</span> <span class="k">with</span> <span class="n">the</span> <span class="n">victims</span> <span class="ow">and</span> <span class="n">relays</span> <span class="n">messages</span> <span class="n">between</span> <span class="n">them</span> <span class="n">to</span> <span class="n">make</span> <span class="n">them</span> <span class="n">believe</span> <span class="n">they</span> <span class="n">are</span> <span class="n">talking</span> <span class="n">directly</span> <span class="n">to</span> <span class="n">each</span> <span class="n">other</span> <span class="n">over</span> <span class="n">a</span> <span class="n">private</span> <span class="n">connection</span><span class="p">,</span> <span class="n">when</span> <span class="ow">in</span> <span class="n">fact</span> <span class="n">the</span> <span class="n">entire</span> <span class="n">conversation</span> <span class="ow">is</span> <span class="n">controlled</span> <span class="n">by</span> <span class="n">the</span> <span class="n">attacker</span><span class="o">.</span> <span class="n">The</span> <span class="n">attacker</span> <span class="n">must</span> <span class="n">be</span> <span class="n">able</span> <span class="n">to</span> <span class="n">intercept</span> <span class="nb">all</span> <span class="n">relevant</span> <span class="n">messages</span> <span class="n">passing</span> <span class="n">between</span> <span class="n">the</span> <span class="n">two</span> <span class="n">victims</span> <span class="ow">and</span> <span class="n">inject</span> <span class="n">new</span> <span class="n">ones</span><span class="o">.</span> <span class="n">This</span> <span class="ow">is</span> <span class="n">straightforward</span> <span class="ow">in</span> <span class="n">many</span> <span class="n">circumstances</span><span class="p">;</span> <span class="k">for</span> <span class="n">example</span><span class="p">,</span> <span class="n">an</span> <span class="n">attacker</span> <span class="n">within</span> <span class="n">reception</span> <span class="nb">range</span> <span class="n">of</span> <span class="n">an</span> <span class="n">unencrypted</span> <span class="n">Wi</span><span class="o">-</span><span class="n">Fi</span> <span class="n">wireless</span> <span class="n">access</span> <span class="n">point</span><span class="p">,</span> <span class="n">can</span> <span class="n">insert</span> <span class="n">himself</span> <span class="k">as</span> <span class="n">a</span> <span class="n">man</span><span class="o">-</span><span class="ow">in</span><span class="o">-</span><span class="n">the</span><span class="o">-</span><span class="n">middle</span><span class="o">.</span>
</pre></div>
</div>
<p>This is quite a generic description, mostly because ( if we're talking about network MITM attacks ), the logic and details heavily rely on the technique being used ( more in the spoofing section ).</p>
<p>Nevertheless we can simplify the concept with an example. When you connect to some network ( your home network, some public WiFi, StarBucks, etc ), the router/switch is responsible for forwarding all of your packets to the correct destination, during a MITM attack we &quot;force&quot; the network to consider our device as the router ( we &quot;spoof&quot; the original router/switch address in some way ):</p>
<p><img alt="network mitm" src="/legacy/assets/img/mitm.jpg" /></p>
<p>Once this happens, all of the network traffic goes through your computer instead of the legit router/switch and at that point you can do pretty much everything you want, from just sniffing for specific data ( emails, passwords, cookies, etc of other people on your network ) to actively intercepting and proxying all the requests of some specific protocol in order to modify them on the fly ( you can, for instance, replace all images of all websites being visited by everyone, kill connections, etc ).</p>
<p>BetterCap is responsible for giving the security researcher everything he needs in <strong>one single tool</strong> which simply works, on GNU/Linux, Mac OS X and OpenBSD systems.</p>
</div>
<div class="section" id="use-cases">
<span id="use-cases"></span><h3>Use Cases<a class="headerlink" href="#use-cases" title="Permalink to this headline">¶</a></h3>
<p>You might think that BetterCAP is just another tool which helps script-kiddies to harm networks ... but it's much more than that, its use cases are many, for instance:</p>
<ul class="simple">
<li>Many professional penetration testers find a great companion in bettercap since its very first release.</li>
<li>Reverse engineers are using it in order to reverse or modify closed network protocols.</li>
<li>Mobile/IoT security researchers are exploiting bettercap capabilities to test the security of mobile systems.</li>
</ul>
</div>
<div class="section" id="why-another-mitm-tool">
<span id="why-another-mitm-tool"></span><h3>Why another MITM tool?<a class="headerlink" href="#why-another-mitm-tool" title="Permalink to this headline">¶</a></h3>
<p>This is exactly what you are thinking right now, isn't it? :D But allow yourself to think about it for 5 more minutes ... what you should be really asking is:</p>
<blockquote>
<div>Does a complete, modular, portable and easy to extend MITM tool actually exist?</div></blockquote>
<p>If your answer is &quot;ettercap&quot;, let me tell you something:</p>
<ul class="simple">
<li>Ettercap was a great tool, but it made its time.</li>
<li>Ettercap filters do not work most of the times, are outdated and hard to implement due to the specific language they're implemented in.</li>
<li>Ettercap is freaking unstable on big networks ... try to launch the host discovery on a bigger network rather than the usual /24 ;)</li>
<li>Yeah you can see connections and raw pcap stuff, nice toy, but as a professional researcher I want to see only relevant stuff.</li>
<li>Unless you're a C/C++ developer, you can't easily extend ettercap or make your own module.</li>
</ul>
<p>Moreover:</p>
<ul class="simple">
<li>Ettercap's and MITMf's ICMP spoofing is completely useless, <a class="reference external" href="http://www.evilsocket.net/2016/01/10/bettercap-and-the-first-real-icmp-redirect-attack/">ours is not</a>.</li>
<li>Ettercap does <strong>not</strong> provide a builtin and modular HTTP(S) and TCP transparent proxies, we do.</li>
<li>Ettercap does <strong>not</strong> provide a smart and fully customizable credentials sniffer, we do.</li>
</ul>
</div>
</div>
<span id="document-install"></span><div class="section" id="installation">
<span id="installation"></span><h2>Installation<a class="headerlink" href="#installation" title="Permalink to this headline">¶</a></h2>
<p>BetterCap comes packaged as a <strong>Ruby</strong> gem, meaning you will need a Ruby interpreter ( &gt;= 1.9 ) and a RubyGems environment installed. Moreover, it is <strong>fully compatible with GNU/Linux, Mac OS X and OpenBSD platforms</strong>.</p>
<div class="section" id="dependencies">
<span id="dependencies"></span><h3>Dependencies<a class="headerlink" href="#dependencies" title="Permalink to this headline">¶</a></h3>
<p>All Ruby dependencies will be automatically installed through the GEM system, however some of the GEMS need native libraries in order to compile:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">sudo</span> <span class="n">apt</span><span class="o">-</span><span class="n">get</span> <span class="n">install</span> <span class="n">build</span><span class="o">-</span><span class="n">essential</span> <span class="n">ruby</span><span class="o">-</span><span class="n">dev</span> <span class="n">libpcap</span><span class="o">-</span><span class="n">dev</span>
</pre></div>
</div>
</div>
<div class="section" id="installing-on-kali-linux">
<span id="installing-on-kali-linux"></span><h3>Installing on Kali Linux<a class="headerlink" href="#installing-on-kali-linux" title="Permalink to this headline">¶</a></h3>
<p>Kali Linux has bettercap packaged and added to the <strong>kali-rolling</strong> repositories. To install bettercap and all dependencies in one fell swoop on the latest version of Kali Linux:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">apt</span><span class="o">-</span><span class="n">get</span> <span class="n">update</span>
<span class="n">apt</span><span class="o">-</span><span class="n">get</span> <span class="n">install</span> <span class="n">bettercap</span>    
</pre></div>
</div>
</div>
<div class="section" id="stable-release-gem">
<span id="stable-release-gem"></span><h3>Stable Release ( GEM )<a class="headerlink" href="#stable-release-gem" title="Permalink to this headline">¶</a></h3>
<p>You can easily install bettercap using the <code class="docutils literal"><span class="pre">gem</span> <span class="pre">install</span> <span class="pre">GEMNAME</span></code> command:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">gem</span> <span class="n">install</span> <span class="n">bettercap</span>
</pre></div>
</div>
<p>To update to a newer release:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">gem</span> <span class="n">update</span> <span class="n">bettercap</span>
</pre></div>
</div>
<p>If you have trouble installing bettercap read the following sections about dependencies.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>If you installed bettercap using a RVM installation, you will need to execute it using <strong>rvmsudo</strong>:<br/>
  <code>rvmsudo bettercap ...</code><br/>
Otherwise, if you installed it globally ( <code>sudo gem install bettercap</code> ) you can use <strong>sudo</strong>:<br/>
  <code>sudo bettercap ...</code>
</p>
</div></div>
<div class="section" id="development-release">
<span id="development-release"></span><h3>Development Release<a class="headerlink" href="#development-release" title="Permalink to this headline">¶</a></h3>
<p>Instead of the stable release, you can also clone the source code from the github repository, this will give you
all the latest and <strong>experimental</strong> features, but remember that you're using a potentially unstable release:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">clone</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">evilsocket</span><span class="o">/</span><span class="n">bettercap</span>
<span class="n">cd</span> <span class="n">bettercap</span>
<span class="n">bundle</span> <span class="n">install</span>
<span class="n">gem</span> <span class="n">build</span> <span class="n">bettercap</span><span class="o">.</span><span class="n">gemspec</span>
<span class="n">sudo</span> <span class="n">gem</span> <span class="n">install</span> <span class="n">bettercap</span><span class="o">*.</span><span class="n">gem</span>
</pre></div>
</div>
</div>
<div class="section" id="quick-start">
<span id="quick-start"></span><h3>Quick Start<a class="headerlink" href="#quick-start" title="Permalink to this headline">¶</a></h3>
<p>Once you've installed bettercap, quickly get started with:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">bettercap</span> <span class="o">--</span><span class="n">help</span>
</pre></div>
</div>
<p>The help menu will show you every available command line option and a few examples.</p>
</div>
</div>
<span id="document-contribute"></span><div class="section" id="contributing">
<span id="contributing"></span><h2>Contributing<a class="headerlink" href="#contributing" title="Permalink to this headline">¶</a></h2>
<p>As any other open source projects, there're many ways you can contribute to bettercap depending on your skills as a developer or will to help as a user.</p>
<div class="section" id="submitting-issues">
<span id="submitting-issues"></span><h3>Submitting Issues<a class="headerlink" href="#submitting-issues" title="Permalink to this headline">¶</a></h3>
<p>If you find bugs or inconsistencies while using bettercap, you can create an <strong>Issue</strong> using the <a class="reference external" href="https://github.com/evilsocket/bettercap/issues">GitHub Issue tracker</a>, but before doing that please make sure that:</p>
<ul class="simple">
<li>You are using a relatively new Ruby version ( &gt;= 1.9 ) : <code class="docutils literal"><span class="pre">ruby</span> <span class="pre">-v</span></code>.</li>
<li>Your GEM environment is configured properly and updated : <code class="docutils literal"><span class="pre">sudo</span> <span class="pre">gem</span> <span class="pre">update</span></code>.</li>
<li>You are using the latest version of bettercap : <code class="docutils literal"><span class="pre">bettercap</span> <span class="pre">--check-updates</span></code>.</li>
<li>The bug you're reporting is actually related to bettercap and not to one of the other GEMs.</li>
</ul>
<p>Once you've gone through this list, open an issue and please give us as much as informations as possible in order for us to fix the bug as soon as possible:</p>
<ul class="simple">
<li>Your OS version.</li>
<li>Ruby version you're using.</li>
<li>Full output of the error ( exception backtrace, error message, etc ).</li>
<li>Your network configuration: <code class="docutils literal"><span class="pre">ifconfig</span> <span class="pre">-a</span></code></li>
</ul>
<p>Also, you should attach to the issue a debug log that you can generate with:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">sudo</span> <span class="n">bettercap</span> <span class="p">[</span><span class="n">arguments</span> <span class="n">you</span> <span class="n">are</span> <span class="n">using</span> <span class="k">for</span> <span class="n">testing</span><span class="p">]</span> <span class="o">--</span><span class="n">debug</span> <span class="o">--</span><span class="n">log</span><span class="o">=</span><span class="n">debug</span><span class="o">.</span><span class="n">log</span>
</pre></div>
</div>
<p>Wait for the error to happen then close bettercap and paste the <strong>debug.log</strong> file inside the issue.</p>
</div>
<div class="section" id="improving-the-documentation">
<span id="improving-the-documentation"></span><h3>Improving the Documentation<a class="headerlink" href="#improving-the-documentation" title="Permalink to this headline">¶</a></h3>
<p>If you want to help, you can improve this documentation cloning <a class="reference external" href="https://github.com/evilsocket/bettercap">our code repository</a> and updating the contents of the <code class="docutils literal"><span class="pre">docs</span></code> folder.</p>
</div>
<div class="section" id="pull-requests">
<span id="pull-requests"></span><h3>Pull Requests<a class="headerlink" href="#pull-requests" title="Permalink to this headline">¶</a></h3>
<p>If you know how to code in Ruby and have ideas to improve bettercap, you're very welcome to send us pull requests, we'll be happy to merge them whenever they comply to the following rules:</p>
<ul class="simple">
<li>You have at least manually tested your code, ideally you've created actual tests for it.</li>
<li>Respect our coding standard, 2 spaces indentation and modular code.</li>
<li>There're no conflicts with the current dev branch.</li>
<li>Your commit messages are enough explanatory to us.</li>
</ul>
<p>There're plenty of things you can to do improve the software:</p>
<ul class="simple">
<li>Implement a new proxy module and push it to the <a class="reference external" href="https://github.com/evilsocket/bettercap-proxy-modules">dedicated repository</a>.</li>
<li>Implement a new <a class="reference external" href="https://github.com/evilsocket/bettercap/blob/master/lib/bettercap/spoofers/arp.rb">Spoofer module</a>.</li>
<li>Implement a new <a class="reference external" href="https://github.com/evilsocket/bettercap/blob/master/lib/bettercap/sniffer/parsers/post.rb">Sniffer credentials parser</a>.</li>
<li>Fix, extend or improve the core.</li>
</ul>
</div>
</div>
</div>
<div class="toctree-wrapper compound">
<span id="document-main"></span><div class="section" id="general-options">
<span id="general-options"></span><h2>General Options<a class="headerlink" href="#general-options" title="Permalink to this headline">¶</a></h2>
<p>The following are the main options that determine the general behaviour of BetterCap, <strong>these options are not mandatory</strong>, in fact bettercap will automatically detect everything it needs in order to work, you just might need to use one or more of the following options to specify some custom behaviour in specific cases.</p>
<div class="section" id="examples">
<span id="examples"></span><h3>Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h3>
<p>Attack specific targets:</p>
<p><code class="docutils literal"><span class="pre">sudo</span> <span class="pre">bettercap</span> <span class="pre">-T</span> <span class="pre">192.168.1.10,192.168.1.11</span></code></p>
<p>Attack a specific target by its MAC address:</p>
<p><code class="docutils literal"><span class="pre">sudo</span> <span class="pre">bettercap</span> <span class="pre">-T</span> <span class="pre">01:23:45:67:89:10</span></code></p>
<p>Attack a range of IP addresses:</p>
<p><code class="docutils literal"><span class="pre">sudo</span> <span class="pre">bettercap</span> <span class="pre">-T</span> <span class="pre">192.168.1.1-30</span></code></p>
<p>Attack a specific subnet:</p>
<p><code class="docutils literal"><span class="pre">sudo</span> <span class="pre">bettercap</span> <span class="pre">-T</span> <span class="pre">192.168.1.1/24</span></code></p>
<p>Randomize the interface MAC address during the attack:</p>
<p><code class="docutils literal"><span class="pre">sudo</span> <span class="pre">bettercap</span> <span class="pre">--random-mac</span></code></p>
</div>
<div class="section" id="options">
<span id="options"></span><h3>Options<a class="headerlink" href="#options" title="Permalink to this headline">¶</a></h3>
<div class="section" id="i-interface-iface">
<span id="i-interface-iface"></span><h4><code class="docutils literal"><span class="pre">-I,</span> <span class="pre">--interface</span> <span class="pre">IFACE</span></code><a class="headerlink" href="#i-interface-iface" title="Permalink to this headline">¶</a></h4>
<p>BetterCAP will automatically detect your default network interface and use it, if you want to make it use another interface ( when you have more than one, let's say <code class="docutils literal"><span class="pre">eth0</span></code> and <code class="docutils literal"><span class="pre">wlan0</span></code> ) you can use this option.</p>
</div>
<div class="section" id="use-mac-address">
<span id="use-mac-address"></span><h4><code class="docutils literal"><span class="pre">--use-mac</span> <span class="pre">ADDRESS</span></code><a class="headerlink" href="#use-mac-address" title="Permalink to this headline">¶</a></h4>
<p>Change the interface MAC address to this value before performing the attack.</p>
</div>
<div class="section" id="random-mac">
<span id="random-mac"></span><h4><code class="docutils literal"><span class="pre">--random-mac</span></code><a class="headerlink" href="#random-mac" title="Permalink to this headline">¶</a></h4>
<p>Change the interface MAC address to a random one before performing the attack.</p>
</div>
<div class="section" id="g-gateway-address">
<span id="g-gateway-address"></span><h4><code class="docutils literal"><span class="pre">-G,</span> <span class="pre">--gateway</span> <span class="pre">ADDRESS</span></code><a class="headerlink" href="#g-gateway-address" title="Permalink to this headline">¶</a></h4>
<p>The same goes for the gateway, either let bettercap automatically detect it or manually specify its address.</p>
</div>
<div class="section" id="t-target-address1-address2">
<span id="t-target-address1-address2"></span><h4><code class="docutils literal"><span class="pre">-T,</span> <span class="pre">--target</span> <span class="pre">ADDRESS1,ADDRESS2</span></code><a class="headerlink" href="#t-target-address1-address2" title="Permalink to this headline">¶</a></h4>
<p>If no specific target is given on the command line, bettercap will spoof every single address on the network. There are cases when you already know the IP or MAC address of your target(s), in such cases you can use this option.</p>
</div>
<div class="section" id="ignore-address1-address2">
<span id="ignore-address1-address2"></span><h4><code class="docutils literal"><span class="pre">--ignore</span> <span class="pre">ADDRESS1,ADDRESS2</span></code><a class="headerlink" href="#ignore-address1-address2" title="Permalink to this headline">¶</a></h4>
<p>Ignore these IP addresses if found while searching for targets.</p>
</div>
<div class="section" id="no-discovery">
<span id="no-discovery"></span><h4><code class="docutils literal"><span class="pre">--no-discovery</span></code><a class="headerlink" href="#no-discovery" title="Permalink to this headline">¶</a></h4>
<p>Do not actively search for hosts, just use the current ARP cache, default to <code class="docutils literal"><span class="pre">false</span></code>.</p>
</div>
<div class="section" id="no-target-nbns">
<span id="no-target-nbns"></span><h4><code class="docutils literal"><span class="pre">--no-target-nbns</span></code><a class="headerlink" href="#no-target-nbns" title="Permalink to this headline">¶</a></h4>
<p>Disable target NBNS hostname resolution.</p>
</div>
<div class="section" id="packet-throttle-number">
<span id="packet-throttle-number"></span><h4><code class="docutils literal"><span class="pre">--packet-throttle</span> <span class="pre">NUMBER</span></code><a class="headerlink" href="#packet-throttle-number" title="Permalink to this headline">¶</a></h4>
<p>Number of seconds ( can be a decimal number ) to wait between each packet to be sent.</p>
</div>
<div class="section" id="check-updates">
<span id="check-updates"></span><h4><code class="docutils literal"><span class="pre">--check-updates</span></code><a class="headerlink" href="#check-updates" title="Permalink to this headline">¶</a></h4>
<p>Will check if any update is available and then exit.</p>
</div>
<div class="section" id="h-help">
<span id="h-help"></span><h4><code class="docutils literal"><span class="pre">-h,</span> <span class="pre">--help</span></code><a class="headerlink" href="#h-help" title="Permalink to this headline">¶</a></h4>
<p>Display the available options.</p>
</div>
</div>
</div>
<span id="document-logging"></span><div class="section" id="logging">
<span id="logging"></span><h2>Logging<a class="headerlink" href="#logging" title="Permalink to this headline">¶</a></h2>
<p>These options determine how bettercap console logger is going to behave.</p>
<div class="section" id="examples">
<span id="examples"></span><h3>Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h3>
<p>Save log output to the <code class="docutils literal"><span class="pre">out.log</span></code> file:</p>
<p><code class="docutils literal"><span class="pre">sudo</span> <span class="pre">bettercap</span> <span class="pre">--log</span> <span class="pre">out.log</span></code></p>
<p>Save log output to the <code class="docutils literal"><span class="pre">out.log</span></code> file and suppress terminal output:</p>
<p><code class="docutils literal"><span class="pre">sudo</span> <span class="pre">bettercap</span> <span class="pre">--log</span> <span class="pre">out.log</span> <span class="pre">--silent</span></code></p>
<p>Save log output to the <code class="docutils literal"><span class="pre">out-ts.log</span></code> file and enable timestamps for each line:</p>
<p><code class="docutils literal"><span class="pre">sudo</span> <span class="pre">bettercap</span> <span class="pre">--log-timestamp</span> <span class="pre">--log</span> <span class="pre">out-ts.log</span></code></p>
</div>
<div class="section" id="options">
<span id="options"></span><h3>Options<a class="headerlink" href="#options" title="Permalink to this headline">¶</a></h3>
<div class="section" id="o-log-log-file">
<span id="o-log-log-file"></span><h4><code class="docutils literal"><span class="pre">-O,</span> <span class="pre">--log</span> <span class="pre">LOG_FILE</span></code><a class="headerlink" href="#o-log-log-file" title="Permalink to this headline">¶</a></h4>
<p>Log all messages into a file, if not specified the log messages will be only print into the shell.</p>
</div>
<div class="section" id="log-timestamp">
<span id="log-timestamp"></span><h4><code class="docutils literal"><span class="pre">--log-timestamp</span></code><a class="headerlink" href="#log-timestamp" title="Permalink to this headline">¶</a></h4>
<p>Enable logging with timestamps for each line, disabled by default.</p>
</div>
<div class="section" id="d-debug">
<span id="d-debug"></span><h4><code class="docutils literal"><span class="pre">-D,</span> <span class="pre">--debug</span></code><a class="headerlink" href="#d-debug" title="Permalink to this headline">¶</a></h4>
<p>Enable debug logging, <strong>it is good practice to use this option while reporting a bug</strong> in order to have the full debug log of the program.</p>
</div>
<div class="section" id="silent">
<span id="silent"></span><h4><code class="docutils literal"><span class="pre">--silent</span></code><a class="headerlink" href="#silent" title="Permalink to this headline">¶</a></h4>
<p>Suppress every message which is not an error or a warning, default to <code class="docutils literal"><span class="pre">false</span></code>.</p>
</div>
</div>
</div>
<span id="document-spoofing"></span><div class="section" id="spoofing">
<span id="spoofing"></span><h2>Spoofing<a class="headerlink" href="#spoofing" title="Permalink to this headline">¶</a></h2>
<p>As previously described in the introduction section, spoofing is the very hearth of every MITM attack. These options will determine which spoofing technique to use and how to use it.</p>
<p>BetterCap already includes an <a class="reference external" href="https://en.wikipedia.org/wiki/ARP_spoofing">ARP spoofer</a> ( working both in full duplex and half duplex mode which is the default ), a <strong>DNS</strong> spoofer and <strong>the first, fully working and completely automatized <a class="reference external" href="https://blog.zimperium.com/doubledirect-zimperium-discovers-full-duplex-icmp-redirect-attacks-in-the-wild/">ICMP DoubleDirect spoofer</a> in the world</strong></p>
<div class="section" id="examples">
<span id="examples"></span><h3>Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h3>
<p>Use the good old ARP spoofing:</p>
<p><code class="docutils literal"><span class="pre">sudo</span> <span class="pre">bettercap</span></code> or <code class="docutils literal"><span class="pre">sudo</span> <span class="pre">bettercap</span> <span class="pre">-S</span> <span class="pre">ARP</span></code> or <code class="docutils literal"><span class="pre">sudo</span> <span class="pre">bettercap</span> <span class="pre">--spoofer</span> <span class="pre">ARP</span></code></p>
<p>Use a <em>full duplex ICMP redirect</em> spoofing attack:</p>
<p><code class="docutils literal"><span class="pre">sudo</span> <span class="pre">bettercap</span> <span class="pre">-S</span> <span class="pre">ICMP</span></code> or <code class="docutils literal"><span class="pre">sudo</span> <span class="pre">bettercap</span> <span class="pre">--spoofer</span> <span class="pre">ICMP</span></code></p>
<p>Disable spoofing:</p>
<p><code class="docutils literal"><span class="pre">sudo</span> <span class="pre">bettercap</span> <span class="pre">-S</span> <span class="pre">NONE</span></code> or <code class="docutils literal"><span class="pre">sudo</span> <span class="pre">bettercap</span> <span class="pre">--spoofer</span> <span class="pre">NONE</span></code> or <code class="docutils literal"><span class="pre">sudo</span> <span class="pre">bettercap</span> <span class="pre">--no-spoofing</span></code></p>
<p>No dear 192.168.1.2, you won't connect to anything anymore :D</p>
<p><code class="docutils literal"><span class="pre">sudo</span> <span class="pre">bettercap</span> <span class="pre">-T</span> <span class="pre">192.168.1.2</span> <span class="pre">--kill</span></code></p>
</div>
<div class="section" id="options">
<span id="options"></span><h3>Options<a class="headerlink" href="#options" title="Permalink to this headline">¶</a></h3>
<div class="section" id="s-spoofer-name">
<span id="s-spoofer-name"></span><h4><code class="docutils literal"><span class="pre">-S,</span> <span class="pre">--spoofer</span> <span class="pre">NAME</span></code><a class="headerlink" href="#s-spoofer-name" title="Permalink to this headline">¶</a></h4>
<p>Spoofer module to use, available: <code class="docutils literal"><span class="pre">ARP</span></code>, <code class="docutils literal"><span class="pre">ICMP</span></code>, <code class="docutils literal"><span class="pre">NONE</span></code> - default: <code class="docutils literal"><span class="pre">ARP</span></code>.</p>
</div>
<div class="section" id="no-spoofing">
<span id="no-spoofing"></span><h4><code class="docutils literal"><span class="pre">--no-spoofing</span></code><a class="headerlink" href="#no-spoofing" title="Permalink to this headline">¶</a></h4>
<p>Disable spoofing, alias for <code class="docutils literal"><span class="pre">--spoofer</span> <span class="pre">NONE</span></code> / <code class="docutils literal"><span class="pre">-S</span> <span class="pre">NONE</span></code>.</p>
</div>
<div class="section" id="kill">
<span id="kill"></span><h4><code class="docutils literal"><span class="pre">--kill</span></code><a class="headerlink" href="#kill" title="Permalink to this headline">¶</a></h4>
<p>Instead of forwarding packets, this switch will make targets connections to be killed.</p>
</div>
<div class="section" id="full-duplex">
<span id="full-duplex"></span><h4><code class="docutils literal"><span class="pre">--full-duplex</span></code><a class="headerlink" href="#full-duplex" title="Permalink to this headline">¶</a></h4>
<p>Enable full-duplex MITM, this will make bettercap attack both the target(s) and the router.</p>
</div>
</div>
</div>
<span id="document-sniffing"></span><div class="section" id="sniffing-credentials-harvesting">
<span id="sniffing-credentials-harvesting"></span><h2>Sniffing &amp; Credentials Harvesting<a class="headerlink" href="#sniffing-credentials-harvesting" title="Permalink to this headline">¶</a></h2>
<p>The builtin sniffer is currently able to dissect and print from the network ( or from a previously captured PCAP file ) the following informations:</p>
<ul class="simple">
<li>URLs being visited.</li>
<li>HTTPS hosts being visited.</li>
<li>HTTP POSTed data.</li>
<li>HTTP Basic and Digest authentications.</li>
<li>HTTP Cookies.</li>
<li>FTP credentials.</li>
<li>IRC credentials.</li>
<li>POP, IMAP and SMTP credentials.</li>
<li>NTLMv1/v2 ( HTTP, SMB, LDAP, etc ) credentials.</li>
<li>DICT Protocol credentials.</li>
<li>MPD Credentials.</li>
<li>NNTP Credentials.</li>
<li>DHCP messages and authentication.</li>
<li>REDIS login credentials.</li>
<li>RLOGIN credentials.</li>
<li>SNPP credentials.</li>
<li>And more!</li>
</ul>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>New parsers are implemented almost on a regular basis for each new release, for a full and updated list check the SNIFFING section in the "bettercap --help" menu.</p>
</div><div class="section" id="examples">
<span id="examples"></span><h3>Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h3>
<p>Use bettercap as a simple local network sniffer:</p>
<p><code class="docutils literal"><span class="pre">sudo</span> <span class="pre">bettercap</span> <span class="pre">--local</span></code> or <code class="docutils literal"><span class="pre">sudo</span> <span class="pre">bettercap</span> <span class="pre">-L</span></code></p>
<p>Use the <em>capture.pcap</em> file in your home directory as a packets source:</p>
<p><code class="docutils literal"><span class="pre">sudo</span> <span class="pre">bettercap</span> <span class="pre">--sniffer-source</span> <span class="pre">~/capture.pcap</span></code></p>
<p>Spoof the whole network and save every packet to the <em>capture.pcap</em> file in your home directory:</p>
<p><code class="docutils literal"><span class="pre">sudo</span> <span class="pre">bettercap</span> <span class="pre">--sniffer-output</span> <span class="pre">~/capture.pcap</span></code></p>
<p>Spoof the whole network but only sniff HTTP traffic:</p>
<p><code class="docutils literal"><span class="pre">sudo</span> <span class="pre">bettercap</span> <span class="pre">--sniffer-filter</span> <span class="pre">&quot;tcp</span> <span class="pre">port</span> <span class="pre">http&quot;</span></code></p>
<p>Spoof the whole network and extract data from packets containing the &quot;password&quot; word:</p>
<p><code class="docutils literal"><span class="pre">sudo</span> <span class="pre">bettercap</span> <span class="pre">--custom-parser</span> <span class="pre">&quot;.*password.*&quot;</span></code></p>
</div>
<div class="section" id="options">
<span id="options"></span><h3>Options<a class="headerlink" href="#options" title="Permalink to this headline">¶</a></h3>
<div class="section" id="x-sniffer">
<span id="x-sniffer"></span><h4><code class="docutils literal"><span class="pre">-X,</span> <span class="pre">--sniffer</span></code><a class="headerlink" href="#x-sniffer" title="Permalink to this headline">¶</a></h4>
<p>Enable sniffer.</p>
</div>
<div class="section" id="l-local">
<span id="l-local"></span><h4><code class="docutils literal"><span class="pre">-L,</span> <span class="pre">--local</span></code><a class="headerlink" href="#l-local" title="Permalink to this headline">¶</a></h4>
<p>By default bettercap will only parse packets coming from/to other addresses on the network, if you also want to process packets being sent or received from your own computer you can use this option ( NOTE: will enable the sniffer ).</p>
</div>
<div class="section" id="sniffer-source-file">
<span id="sniffer-source-file"></span><h4><code class="docutils literal"><span class="pre">--sniffer-source</span> <span class="pre">FILE</span></code><a class="headerlink" href="#sniffer-source-file" title="Permalink to this headline">¶</a></h4>
<p>Load packets from the specified PCAP file instead of the network interface ( NOTE: will enable the sniffer ).</p>
</div>
<div class="section" id="sniffer-output-file">
<span id="sniffer-output-file"></span><h4><code class="docutils literal"><span class="pre">--sniffer-output</span> <span class="pre">FILE</span></code><a class="headerlink" href="#sniffer-output-file" title="Permalink to this headline">¶</a></h4>
<p>Save all packets to the specified PCAP file ( NOTE: will enable the sniffer ).</p>
</div>
<div class="section" id="sniffer-filter-expression">
<span id="sniffer-filter-expression"></span><h4><code class="docutils literal"><span class="pre">--sniffer-filter</span> <span class="pre">EXPRESSION</span></code><a class="headerlink" href="#sniffer-filter-expression" title="Permalink to this headline">¶</a></h4>
<p>Configure the sniffer to use this <a class="reference external" href="http://biot.com/capstats/bpf.html">BPF filter</a> ( NOTE: will enable the sniffer ).</p>
</div>
<div class="section" id="p-parsers-parsers">
<span id="p-parsers-parsers"></span><h4><code class="docutils literal"><span class="pre">-P,</span> <span class="pre">--parsers</span> <span class="pre">PARSERS</span></code><a class="headerlink" href="#p-parsers-parsers" title="Permalink to this headline">¶</a></h4>
<p>Comma separated list of packet parsers to enable, <code class="docutils literal"><span class="pre">*</span></code> for all ( NOTE: will enable the sniffer ), available: <code class="docutils literal"><span class="pre">COOKIE</span></code>, <code class="docutils literal"><span class="pre">CREDITCARD</span></code>, <code class="docutils literal"><span class="pre">DHCP</span></code>, <code class="docutils literal"><span class="pre">DICT</span></code>, <code class="docutils literal"><span class="pre">FTP</span></code>, <code class="docutils literal"><span class="pre">HTTPAUTH</span></code>, <code class="docutils literal"><span class="pre">HTTPS</span></code>, <code class="docutils literal"><span class="pre">IRC</span></code>, <code class="docutils literal"><span class="pre">MAIL</span></code>, <code class="docutils literal"><span class="pre">MPD</span></code>, <code class="docutils literal"><span class="pre">MYSQL</span></code>, <code class="docutils literal"><span class="pre">NNTP</span></code>, <code class="docutils literal"><span class="pre">NTLMSS</span></code>, <code class="docutils literal"><span class="pre">PGSQL</span></code>, <code class="docutils literal"><span class="pre">POST</span></code>, <code class="docutils literal"><span class="pre">REDIS</span></code>, <code class="docutils literal"><span class="pre">RLOGIN</span></code>, <code class="docutils literal"><span class="pre">SNMP</span></code>, <code class="docutils literal"><span class="pre">SNPP</span></code>, <code class="docutils literal"><span class="pre">URL</span></code>, <code class="docutils literal"><span class="pre">WHATSAPP</span></code>, default to <code class="docutils literal"><span class="pre">*</span></code>.</p>
</div>
<div class="section" id="custom-parser-expression">
<span id="custom-parser-expression"></span><h4><code class="docutils literal"><span class="pre">--custom-parser</span> <span class="pre">EXPRESSION</span></code><a class="headerlink" href="#custom-parser-expression" title="Permalink to this headline">¶</a></h4>
<p>Use a custom regular expression in order to capture and show sniffed data ( NOTE: will enable the sniffer ).</p>
</div>
</div>
</div>
</div>
<div class="toctree-wrapper compound">
<span id="document-proxying"></span><div class="section" id="about-proxying">
<span id="about-proxying"></span><h2>About Proxying<a class="headerlink" href="#about-proxying" title="Permalink to this headline">¶</a></h2>
<p>Bettercap is shipped with a HTTP/HTTPS ( with <strong>SSL Stripping</strong> and <strong>HSTS Bypass</strong> ) and raw TCP transparent proxies that you can use to manipulate HTTP/HTTPS or low level TCP traffic at runtime, for instance you could use the HTTP/HTTPS proxy to inject javascripts into the targets visited pages ( <a class="reference external" href="http://beefproject.com/">BeEF</a> would be a great choice :D ), replace all the images, etc or use the TCP one for other protocols ( downgrade encryption with STARTTLS, dump custom protocols and so forth.</p>
<p><img alt="proxy" src="/legacy/assets/img/proxy.png" /></p>
<p>Once one or more proxies are enabled, bettercap will take care of the spoofing and the firewall rules needed in order to redirect your targets' traffic to the proxy itself.</p>
<p>By default the builtin proxies won't do anything but logging all the requests, additionally you can specify a &quot;module&quot; to use and you will be able to load one of the builtin plugins ( or your own ) and manipulate all the traffic as you like.</p>
</div>
<span id="document-proxying/http"></span><div class="section" id="http-https">
<span id="http-https"></span><h2>HTTP/HTTPS<a class="headerlink" href="#http-https" title="Permalink to this headline">¶</a></h2>
<p>Bettercap is shipped with both a HTTP and a HTTPS transparent proxies that you can use to manipulate HTTP and HTTPS traffic at runtime ( inject javascripts into the targets visited pages, replace the images, etc ).
By default the builtin proxies won't do anything but logging HTTP(S) requests, but if you specify a <code class="docutils literal"><span class="pre">--proxy-module</span></code> argument you will be able to load one of the builtin modules ( or your own ) and manipulate HTTP traffic as you like.</p>
<p>Builtin modules are:</p>
<ul class="simple">
<li>InjectJS ( <code class="docutils literal"><span class="pre">--proxy-module</span> <span class="pre">injectjs</span></code> ) : Used to inject javascript code/files inside HTML pages.</li>
<li>InjectCSS ( <code class="docutils literal"><span class="pre">--proxy-module</span> <span class="pre">injectcss</span></code> ) : Used to inject CSS code/files inside HTML pages.</li>
<li>InjectHTML ( <code class="docutils literal"><span class="pre">--proxy-module</span> <span class="pre">injecthtml</span></code> ) : Used to inject HTML code inside HTML pages.</li>
</ul>
<p>HTTP/HTTPS proxy modules might want additional command line arguments, it's always a good idea to look at their specific help menus:</p>
<p><code class="docutils literal"><span class="pre">bettercap</span> <span class="pre">--proxy-module</span> <span class="pre">NAME</span> <span class="pre">-h</span></code></p>
<div class="section" id="sample-module">
<span id="sample-module"></span><h3>Sample Module<a class="headerlink" href="#sample-module" title="Permalink to this headline">¶</a></h3>
<p>You can easily implement a module to inject data into pages or just inspect the requests/responses creating a ruby file and passing it to bettercap with the <code class="docutils literal"><span class="pre">--proxy-module</span></code> argument, the following is a sample module that injects some contents into the title tag of each html page, you can find other examples modules in the <a class="reference external" href="https://github.com/evilsocket/bettercap-proxy-modules">proxy modules dedicated repository</a>.</p>
<script src="https://gist.github.com/evilsocket/bfdb1af7e6bf9d9d0bfe.js"></script></div>
<div class="section" id="http">
<span id="http"></span><h3>HTTP<a class="headerlink" href="#http" title="Permalink to this headline">¶</a></h3>
<div class="section" id="ssl-stripping">
<span id="ssl-stripping"></span><h4>SSL Stripping<a class="headerlink" href="#ssl-stripping" title="Permalink to this headline">¶</a></h4>
<p>SSL stripping is a technique introduced by <a class="reference external" href="http://www.thoughtcrime.org/software/sslstrip/">Moxie Marlinspike</a> during BlackHat DC 2009, the website description of this technique goes like:</p>
<blockquote>
<div>It will transparently hijack HTTP traffic on a network, watch for HTTPS links and redirects, then map those links into either look-alike HTTP links or homograph-similar HTTPS links.</div></blockquote>
<p>Long story short, this technique will replace every <strong>https</strong> link in webpages the target is browsing with <strong>http</strong> ones so, if a page would normally look like:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="o">...</span> <span class="o">&lt;</span><span class="n">a</span> <span class="n">href</span><span class="o">=</span><span class="s2">&quot;https://www.facebook.com/&quot;</span><span class="o">&gt;</span><span class="n">Login</span><span class="o">&lt;/</span><span class="n">a</span><span class="o">&gt;</span> <span class="o">...</span>
</pre></div>
</div>
<p>During a SSL stripping attack its HTML code will be modified as:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="o">...</span> <span class="o">&lt;</span><span class="n">a</span> <span class="n">href</span><span class="o">=</span><span class="s2">&quot;http://www.facebook.com/&quot;</span><span class="o">&gt;</span><span class="n">Login</span><span class="o">&lt;/</span><span class="n">a</span><span class="o">&gt;</span> <span class="o">...</span>
</pre></div>
</div>
<p>Being the <strong>man in the middle</strong>, this allow us to sniff and modify pages that normally we wouldn't be able to even see.</p>
</div>
<div class="section" id="hsts-bypass">
<span id="hsts-bypass"></span><h4>HSTS Bypass<a class="headerlink" href="#hsts-bypass" title="Permalink to this headline">¶</a></h4>
<p>SSL stripping worked quite well until 2010, when the <strong>HSTS</strong> specification was introduced, Wikipedia says:</p>
<blockquote>
<div><strong>HTTP Strict Transport Security</strong> (HSTS) is a web security policy mechanism which helps to protect websites against protocol downgrade attacks and cookie hijacking. It allows web servers to declare that web browsers (or other complying user agents) should only interact with it using secure HTTPS connections, and never via the insecure HTTP protocol. HSTS is an IETF standards track protocol and is specified in RFC 6797.</div></blockquote>
<p>Moreover HSTS policies have been prebuilt into major browsers meaning that now, even with a SSL stripping attack running, the browser will
connect to HTTPS anyway, even if the <em>http://</em> schema is specified, making the attack itself useless.</p>
<p><center>
<img alt="network mitm" src="/legacy/assets/img/with-hsts.png" />
<br/>
<small>Picture credits to <a href="https://scotthelme.co.uk/ssl-does-not-make-site-secure/" target="_blank">Scott Helme</a></small>
</center></p>
<p>For this reason, <a class="reference external" href="http://www.slideshare.net/Fatuo__/offensive-exploiting-dns-servers-changes-blackhat-asia-2014">Leonardo Nve Egea</a> presented <strong>sslstrip+</strong> ( or sslstrip2 ) during BlackHat Asia 2014.
This tool was an improvement over the original Moxie's version, specifically created to bypass HSTS policies.
Since HSTS rules most of the time are applied on a per-hostname basis, the trick is to downgrade HTTPS links to HTTP <strong>and</strong> to prepend some custom sub domain name to them. Every resulting link won't be valid for any DNS server, but since we're MITMing we can resolve these hostnames anyway.</p>
<p>Let's take the previous example page:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="o">...</span> <span class="o">&lt;</span><span class="n">a</span> <span class="n">href</span><span class="o">=</span><span class="s2">&quot;https://www.facebook.com/&quot;</span><span class="o">&gt;</span><span class="n">Login</span><span class="o">&lt;/</span><span class="n">a</span><span class="o">&gt;</span> <span class="o">...</span>
</pre></div>
</div>
<p>A HSTS bypass attack will change it to something like:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="o">...</span> <span class="o">&lt;</span><span class="n">a</span> <span class="n">href</span><span class="o">=</span><span class="s2">&quot;http://wwww.facebook.com/&quot;</span><span class="o">&gt;</span><span class="n">Login</span><span class="o">&lt;/</span><span class="n">a</span><span class="o">&gt;</span> <span class="o">...</span>
</pre></div>
</div>
<p><center><small>Notice that https has been downgraded to http and <strong>www</strong> replaced with <strong>wwww</strong> ).</small></center></p>
<p>When the &quot;victim&quot; will click on that link, no HSTS rule will be applied ( since there's no rule for such subdomain we just created ) and the MITM software ( BetterCap in our case ^_^ ) will take care of the DNS resolution, allowing us to see and alter the traffic we weren't supposed to see.</p>
<p><center>
<img alt="network mitm" src="/legacy/assets/img/sslstrip2.png" />
</center></p>
</div>
<div class="section" id="demonstration">
<span id="demonstration"></span><h4>Demonstration<a class="headerlink" href="#demonstration" title="Permalink to this headline">¶</a></h4>
<p>The following video demonstrates how to perform SSL Stripping and HSTS Bypass attacks in order to capture the Facebook login credentials of a specific target.</p>
<iframe width="100%" height="400" src="https://www.youtube.com/embed/BfvoONHXuQA" frameborder="0" allowfullscreen></iframe></div>
</div>
<div class="section" id="https">
<span id="https"></span><h3>HTTPS<a class="headerlink" href="#https" title="Permalink to this headline">¶</a></h3>
<div class="section" id="server-name-indication">
<span id="server-name-indication"></span><h4>Server Name Indication<a class="headerlink" href="#server-name-indication" title="Permalink to this headline">¶</a></h4>
<blockquote>
<div>Server Name Indication (SNI) is an extension to the TLS computer networking protocol by which a client indicates which hostname it is attempting to connect to at the start of the handshaking process. This allows a server to present multiple certificates on the same IP address and TCP port number and hence allows multiple secure (HTTPS) websites (or any other Service over TLS) to be served off the same IP address without requiring all those sites to use the same certificate.</div></blockquote>
<p>Using the <strong>SNI</strong> callback, BetterCAP's HTTPS proxy is able to detect the upstream server host using the following logic:</p>
<ol class="simple">
<li>Client connects to a HTTPS server while being transparently proxied by us.</li>
<li>We catch the upstream server hostname in the <strong>SNI</strong> callback.</li>
<li>We pause the callback, connect to the upstream server and fetch its certificate.</li>
<li>We resign that certificate with our own CA and use it to serve the client.</li>
</ol>
<p>This way, as long as you have BetterCap's certification authority PEM file installed on the target device, you won't see any warnings or errors since correct certificate will be spoofed in realtime.</p>
<p>There're a couple of caveats of course:</p>
<ol class="simple">
<li>If you don't install either bettercap's CA or your custom CA on the target device, you'll see warnings and errors anyway (duh!).</li>
<li>Every application using <a class="reference external" href="https://www.owasp.org/index.php/Certificate_and_Public_Key_Pinning">certificate/public Key pinning</a> will detect the attack even with the CA installed.</li>
</ol>
</div>
<div class="section" id="installing-certification-authority">
<span id="installing-certification-authority"></span><h4>Installing Certification Authority<a class="headerlink" href="#installing-certification-authority" title="Permalink to this headline">¶</a></h4>
<p>Since version 1.4.4 BetterCAP comes with a pre made certification authority file which is extracted in your home directory the first time you'll launch the HTTPS proxy, you'll find the file as:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="o">~/.</span><span class="n">bettercap</span><span class="o">/</span><span class="n">bettercap</span><span class="o">-</span><span class="n">ca</span><span class="o">.</span><span class="n">pem</span>
</pre></div>
</div>
<p>You'll need to install this file on the device you want to transparently proxy HTTPS connection for, the procedure is OS specific as mentioned in a previous blog post:</p>
<ul class="simple">
<li><strong>iOS</strong> - http://kb.mit.edu/confluence/pages/viewpage.action?pageId=152600377</li>
<li><strong>iOS Simulator</strong> - https://github.com/ADVTOOLS/ADVTrustStore#how-to-use-advtruststore</li>
<li><strong>Java</strong> - http://docs.oracle.com/cd/E19906-01/820-4916/geygn/index.html</li>
<li><strong>Android/Android Simulator</strong> - http://wiki.cacert.org/FAQ/ImportRootCert#Android_Phones_.26_Tablets</li>
<li><strong>Windows</strong> - http://windows.microsoft.com/en-ca/windows/import-export-certificates-private-keys#1TC=windows-7</li>
<li><strong>Mac OS X</strong> - https://support.apple.com/kb/PH7297?locale=en_US</li>
<li><strong>Ubuntu/Debian</strong> - http://askubuntu.com/questions/73287/how-do-i-install-a-root-certificate/94861#94861</li>
<li><strong>Mozilla Firefox</strong> - https://wiki.mozilla.org/MozillaRootCertificate#Mozilla_Firefox</li>
<li><strong>Chrome on Linux</strong> - https://code.google.com/p/chromium/wiki/LinuxCertManagement</li>
</ul>
<p>Once you've done, just use the <code class="docutils literal"><span class="pre">--proxy-https</span></code> bettercap command line argument to enable the HTTPS proxy and you're ready to go.</p>
<hr/></div>
</div>
<div class="section" id="options">
<span id="options"></span><h3>Options<a class="headerlink" href="#options" title="Permalink to this headline">¶</a></h3>
<div class="section" id="proxy-upstream-address-address">
<span id="proxy-upstream-address-address"></span><h4><code class="docutils literal"><span class="pre">--proxy-upstream-address</span> <span class="pre">ADDRESS</span></code><a class="headerlink" href="#proxy-upstream-address-address" title="Permalink to this headline">¶</a></h4>
<p>If set, only requests coming from this server address will be redirected to the HTTP/HTTPS proxies.</p>
</div>
<div class="section" id="allow-local-connections">
<span id="allow-local-connections"></span><h4><code class="docutils literal"><span class="pre">--allow-local-connections</span></code><a class="headerlink" href="#allow-local-connections" title="Permalink to this headline">¶</a></h4>
<p>Allow direct connections to the proxy instance, default to <code class="docutils literal"><span class="pre">false</span></code>.</p>
</div>
<div class="section" id="proxy">
<span id="proxy"></span><h4><code class="docutils literal"><span class="pre">--proxy</span></code><a class="headerlink" href="#proxy" title="Permalink to this headline">¶</a></h4>
<p>Enable HTTP proxy and redirects all HTTP requests to it, default to <code class="docutils literal"><span class="pre">false</span></code>.</p>
</div>
<div class="section" id="proxy-port-port">
<span id="proxy-port-port"></span><h4><code class="docutils literal"><span class="pre">--proxy-port</span> <span class="pre">PORT</span></code><a class="headerlink" href="#proxy-port-port" title="Permalink to this headline">¶</a></h4>
<p>Set HTTP proxy port, default to <code class="docutils literal"><span class="pre">8080</span></code>.</p>
</div>
<div class="section" id="no-sslstrip">
<span id="no-sslstrip"></span><h4><code class="docutils literal"><span class="pre">--no-sslstrip</span></code><a class="headerlink" href="#no-sslstrip" title="Permalink to this headline">¶</a></h4>
<p>Disable SSL stripping and HSTS bypass.</p>
</div>
<div class="section" id="log-http-response">
<span id="log-http-response"></span><h4><code class="docutils literal"><span class="pre">--log-http-response</span></code><a class="headerlink" href="#log-http-response" title="Permalink to this headline">¶</a></h4>
<p>Log HTTP responses.</p>
</div>
<div class="section" id="proxy-module-module">
<span id="proxy-module-module"></span><h4><code class="docutils literal"><span class="pre">--proxy-module</span> <span class="pre">MODULE</span></code><a class="headerlink" href="#proxy-module-module" title="Permalink to this headline">¶</a></h4>
<p>Ruby proxy module to load, either a custom file or one of the following: <code class="docutils literal"><span class="pre">injectcss</span></code>, <code class="docutils literal"><span class="pre">injecthtml</span></code>, <code class="docutils literal"><span class="pre">injectjs</span></code>.</p>
</div>
<div class="section" id="http-ports-port1-port2">
<span id="http-ports-port1-port2"></span><h4><code class="docutils literal"><span class="pre">--http-ports</span> <span class="pre">PORT1,PORT2</span></code><a class="headerlink" href="#http-ports-port1-port2" title="Permalink to this headline">¶</a></h4>
<p>Comma separated list of HTTP ports to redirect to the proxy, default to <code class="docutils literal"><span class="pre">80</span></code>.</p>
</div>
<div class="section" id="proxy-https">
<span id="proxy-https"></span><h4><code class="docutils literal"><span class="pre">--proxy-https</span></code><a class="headerlink" href="#proxy-https" title="Permalink to this headline">¶</a></h4>
<p>Enable HTTPS proxy and redirects all HTTPS requests to it, default to <code class="docutils literal"><span class="pre">false</span></code>.</p>
</div>
<div class="section" id="proxy-https-port-port">
<span id="proxy-https-port-port"></span><h4><code class="docutils literal"><span class="pre">--proxy-https-port</span> <span class="pre">PORT</span></code><a class="headerlink" href="#proxy-https-port-port" title="Permalink to this headline">¶</a></h4>
<p>Set HTTPS proxy port, default to <code class="docutils literal"><span class="pre">8083</span></code>.</p>
</div>
<div class="section" id="proxy-pem-file">
<span id="proxy-pem-file"></span><h4><code class="docutils literal"><span class="pre">--proxy-pem</span> <span class="pre">FILE</span></code><a class="headerlink" href="#proxy-pem-file" title="Permalink to this headline">¶</a></h4>
<p>Use a custom PEM CA certificate file for the HTTPS proxy, default to <code class="docutils literal"><span class="pre">~/.bettercap/bettercap-ca.pem</span></code>.</p>
</div>
<div class="section" id="https-ports-port1-port2">
<span id="https-ports-port1-port2"></span><h4><code class="docutils literal"><span class="pre">--https-ports</span> <span class="pre">PORT1,PORT2</span></code><a class="headerlink" href="#https-ports-port1-port2" title="Permalink to this headline">¶</a></h4>
<p>Comma separated list of HTTPS ports to redirect to the proxy, default to <code class="docutils literal"><span class="pre">443</span></code>.</p>
</div>
</div>
</div>
<span id="document-proxying/tcp"></span><div class="section" id="tcp">
<span id="tcp"></span><h2>TCP<a class="headerlink" href="#tcp" title="Permalink to this headline">¶</a></h2>
<p>If you want to actively modify packets of a TCP protocol which is not HTTP or HTTPS, you'll need the TCP proxy. This event-based proxy will allow you to intercept anything sent/received to/from a specific host using your own custom module.</p>
<div class="section" id="sample-module">
<span id="sample-module"></span><h3>Sample Module<a class="headerlink" href="#sample-module" title="Permalink to this headline">¶</a></h3>
<p>The following example module won't do anything but dumping the data being transmitted from/to the target, you can access the <a class="reference external" href="http://www.rubydoc.info/gems/bettercap/1.5.0/BetterCap/Proxy/TCP/Event">event</a> object in order to modify the data on the fly.</p>
<script src="https://gist.github.com/evilsocket/36da77e34766dc600218.js"></script><p>If you want to load such module and dump all the ( let's say ) MySQL traffic from/to the <code class="docutils literal"><span class="pre">mysql.example.com</span></code> host you would do:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">sudo</span> <span class="n">bettercap</span> <span class="o">--</span><span class="n">tcp</span><span class="o">-</span><span class="n">proxy</span><span class="o">-</span><span class="n">module</span> <span class="n">example</span><span class="o">.</span><span class="n">rb</span> <span class="o">--</span><span class="n">tcp</span><span class="o">-</span><span class="n">proxy</span><span class="o">-</span><span class="n">upstream</span> <span class="n">mysql</span><span class="o">.</span><span class="n">example</span><span class="o">.</span><span class="n">com</span><span class="p">:</span><span class="mi">3306</span>
</pre></div>
</div>
<p>And you would be ready to go.</p>
<hr/></div>
<div class="section" id="options">
<span id="options"></span><h3>Options<a class="headerlink" href="#options" title="Permalink to this headline">¶</a></h3>
<div class="section" id="tcp-proxy">
<span id="tcp-proxy"></span><h4><code class="docutils literal"><span class="pre">--tcp-proxy</span></code><a class="headerlink" href="#tcp-proxy" title="Permalink to this headline">¶</a></h4>
<p>Enable the TCP proxy ( requires other <code class="docutils literal"><span class="pre">--tcp-proxy-*</span></code> options to be specified ).</p>
</div>
<div class="section" id="tcp-proxy-module-module">
<span id="tcp-proxy-module-module"></span><h4><code class="docutils literal"><span class="pre">--tcp-proxy-module</span> <span class="pre">MODULE</span></code><a class="headerlink" href="#tcp-proxy-module-module" title="Permalink to this headline">¶</a></h4>
<p>Ruby TCP proxy module to load.</p>
</div>
<div class="section" id="tcp-proxy-port-port">
<span id="tcp-proxy-port-port"></span><h4><code class="docutils literal"><span class="pre">--tcp-proxy-port</span> <span class="pre">PORT</span></code><a class="headerlink" href="#tcp-proxy-port-port" title="Permalink to this headline">¶</a></h4>
<p>Set local TCP proxy port, default to <code class="docutils literal"><span class="pre">2222</span></code>.</p>
</div>
<div class="section" id="tcp-proxy-upstream-address-address">
<span id="tcp-proxy-upstream-address-address"></span><h4><code class="docutils literal"><span class="pre">--tcp-proxy-upstream-address</span> <span class="pre">ADDRESS</span></code><a class="headerlink" href="#tcp-proxy-upstream-address-address" title="Permalink to this headline">¶</a></h4>
<p>Set TCP proxy upstream server address.</p>
</div>
<div class="section" id="tcp-proxy-upstream-port-port">
<span id="tcp-proxy-upstream-port-port"></span><h4><code class="docutils literal"><span class="pre">--tcp-proxy-upstream-port</span> <span class="pre">PORT</span></code><a class="headerlink" href="#tcp-proxy-upstream-port-port" title="Permalink to this headline">¶</a></h4>
<p>Set TCP proxy upstream server port.</p>
</div>
<div class="section" id="tcp-proxy-upstream-address-port">
<span id="tcp-proxy-upstream-address-port"></span><h4><code class="docutils literal"><span class="pre">--tcp-proxy-upstream</span> <span class="pre">ADDRESS:PORT</span></code><a class="headerlink" href="#tcp-proxy-upstream-address-port" title="Permalink to this headline">¶</a></h4>
<p>Set TCP proxy upstream server address and port ( shortcut for <code class="docutils literal"><span class="pre">--tcp-proxy-upstream-address</span> <span class="pre">ADDRESS</span></code> and <code class="docutils literal"><span class="pre">--tcp-proxy-upstream-port</span> <span class="pre">PORT</span></code> ).</p>
</div>
</div>
</div>
<span id="document-proxying/udp"></span><div class="section" id="udp">
<span id="udp"></span><h2>UDP<a class="headerlink" href="#udp" title="Permalink to this headline">¶</a></h2>
<p>If you want to actively modify packets of a UDP protocol, you'll need the UDP proxy. This event-based proxy will allow you to intercept anything sent/received to/from a specific host using your own custom module.</p>
<div class="section" id="sample-module">
<span id="sample-module"></span><h3>Sample Module<a class="headerlink" href="#sample-module" title="Permalink to this headline">¶</a></h3>
<p>The following example module won't do anything but dumping the data being transmitted from/to the target, you can access the <a class="reference external" href="http://www.rubydoc.info/gems/bettercap/1.5.0/BetterCap/Proxy/UDP/Event">event</a> object in order to modify the data on the fly.</p>
<script src="https://gist.github.com/evilsocket/7fbbfc9b12826e7de7a1c97a921b7ce8.js"></script><p>If you want to load such module and dump all the ( let's say ) DNS traffic from/to the <code class="docutils literal"><span class="pre">ns01.example.com</span></code> host you would do:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">sudo</span> <span class="n">bettercap</span> <span class="o">--</span><span class="n">udp</span><span class="o">-</span><span class="n">proxy</span><span class="o">-</span><span class="n">module</span> <span class="n">example</span><span class="o">.</span><span class="n">rb</span> <span class="o">--</span><span class="n">udp</span><span class="o">-</span><span class="n">proxy</span><span class="o">-</span><span class="n">upstream</span> <span class="n">ns01</span><span class="o">.</span><span class="n">example</span><span class="o">.</span><span class="n">com</span><span class="p">:</span><span class="mi">53</span>
</pre></div>
</div>
<p>And you would be ready to go.</p>
<hr/></div>
<div class="section" id="options">
<span id="options"></span><h3>Options<a class="headerlink" href="#options" title="Permalink to this headline">¶</a></h3>
<div class="section" id="udp-proxy">
<span id="udp-proxy"></span><h4><code class="docutils literal"><span class="pre">--udp-proxy</span></code><a class="headerlink" href="#udp-proxy" title="Permalink to this headline">¶</a></h4>
<p>Enable the UDP proxy ( requires other <code class="docutils literal"><span class="pre">--udp-proxy-*</span></code> options to be specified ).</p>
</div>
<div class="section" id="udp-proxy-module-module">
<span id="udp-proxy-module-module"></span><h4><code class="docutils literal"><span class="pre">--udp-proxy-module</span> <span class="pre">MODULE</span></code><a class="headerlink" href="#udp-proxy-module-module" title="Permalink to this headline">¶</a></h4>
<p>Ruby UDP proxy module to load.</p>
</div>
<div class="section" id="udp-proxy-port-port">
<span id="udp-proxy-port-port"></span><h4><code class="docutils literal"><span class="pre">--udp-proxy-port</span> <span class="pre">PORT</span></code><a class="headerlink" href="#udp-proxy-port-port" title="Permalink to this headline">¶</a></h4>
<p>Set local UDP proxy port, default to <code class="docutils literal"><span class="pre">2222</span></code>.</p>
</div>
<div class="section" id="udp-proxy-upstream-address-address">
<span id="udp-proxy-upstream-address-address"></span><h4><code class="docutils literal"><span class="pre">--udp-proxy-upstream-address</span> <span class="pre">ADDRESS</span></code><a class="headerlink" href="#udp-proxy-upstream-address-address" title="Permalink to this headline">¶</a></h4>
<p>Set UDP proxy upstream server address.</p>
</div>
<div class="section" id="udp-proxy-upstream-port-port">
<span id="udp-proxy-upstream-port-port"></span><h4><code class="docutils literal"><span class="pre">--udp-proxy-upstream-port</span> <span class="pre">PORT</span></code><a class="headerlink" href="#udp-proxy-upstream-port-port" title="Permalink to this headline">¶</a></h4>
<p>Set UDP proxy upstream server port.</p>
</div>
<div class="section" id="udp-proxy-upstream-address-port">
<span id="udp-proxy-upstream-address-port"></span><h4><code class="docutils literal"><span class="pre">--udp-proxy-upstream</span> <span class="pre">ADDRESS:PORT</span></code><a class="headerlink" href="#udp-proxy-upstream-address-port" title="Permalink to this headline">¶</a></h4>
<p>Set UDP proxy upstream server address and port ( shortcut for <code class="docutils literal"><span class="pre">--udp-proxy-upstream-address</span> <span class="pre">ADDRESS</span></code> and <code class="docutils literal"><span class="pre">--udp-proxy-upstream-port</span> <span class="pre">PORT</span></code> ).</p>
</div>
</div>
</div>
<span id="document-proxying/custom"></span><div class="section" id="third-party-proxies">
<span id="third-party-proxies"></span><h2>Third Party Proxies<a class="headerlink" href="#third-party-proxies" title="Permalink to this headline">¶</a></h2>
<p>If you want to use some custom proxy of yours ( BurpSuite for instance, or some custom app you wrote ) you can still use bettercap to make the whole process easier, no more crappy shell scripts to apply custom firewall rules and launch &quot;esotic&quot; commands!</p>
<p>For instance, if you want to attack the whole network and redirect all HTTP traffic to your local BurpSuite installation ( in this example <code class="docutils literal"><span class="pre">192.168.1.2</span></code> is your computer ip address ):</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">sudo</span> <span class="n">bettercap</span> <span class="o">--</span><span class="n">custom</span><span class="o">-</span><span class="n">proxy</span> <span class="mf">192.168</span><span class="o">.</span><span class="mf">1.2</span>
</pre></div>
</div>
<hr/><div class="section" id="custom-proxy-address">
<span id="custom-proxy-address"></span><h3><code class="docutils literal"><span class="pre">--custom-proxy</span> <span class="pre">ADDRESS</span></code><a class="headerlink" href="#custom-proxy-address" title="Permalink to this headline">¶</a></h3>
<p>Use a custom HTTP upstream proxy instead of the builtin one.</p>
</div>
<div class="section" id="custom-proxy-port-port">
<span id="custom-proxy-port-port"></span><h3><code class="docutils literal"><span class="pre">--custom-proxy-port</span> <span class="pre">PORT</span></code><a class="headerlink" href="#custom-proxy-port-port" title="Permalink to this headline">¶</a></h3>
<p>Specify a port for the custom HTTP upstream proxy, default to <code class="docutils literal"><span class="pre">8080</span></code>.</p>
</div>
<div class="section" id="custom-https-proxy-address">
<span id="custom-https-proxy-address"></span><h3><code class="docutils literal"><span class="pre">--custom-https-proxy</span> <span class="pre">ADDRESS</span></code><a class="headerlink" href="#custom-https-proxy-address" title="Permalink to this headline">¶</a></h3>
<p>Use a custom HTTPS upstream proxy instead of the builtin one.</p>
</div>
<div class="section" id="custom-https-proxy-port-port">
<span id="custom-https-proxy-port-port"></span><h3><code class="docutils literal"><span class="pre">--custom-https-proxy-port</span> <span class="pre">PORT</span></code><a class="headerlink" href="#custom-https-proxy-port-port" title="Permalink to this headline">¶</a></h3>
<p>Specify a port for the custom HTTPS upstream proxy, default to 8083.</p>
</div>
<div class="section" id="custom-redirection-rule">
<span id="custom-redirection-rule"></span><h3><code class="docutils literal"><span class="pre">--custom-redirection</span> <span class="pre">RULE</span></code><a class="headerlink" href="#custom-redirection-rule" title="Permalink to this headline">¶</a></h3>
<p>Apply a custom port redirection, the format of the rule is <code class="docutils literal"><span class="pre">PROTOCOL</span> <span class="pre">ORIGINAL_PORT</span> <span class="pre">NEW_PORT</span></code>.
For instance <code class="docutils literal"><span class="pre">TCP</span> <span class="pre">21</span> <span class="pre">2100</span></code> will redirect all TCP traffic going to port <code class="docutils literal"><span class="pre">21</span></code>, to port <code class="docutils literal"><span class="pre">2100</span></code>.</p>
</div>
</div>
</div>
<div class="toctree-wrapper compound">
<span id="document-servers/http"></span><div class="section" id="http">
<span id="http"></span><h2>HTTP<a class="headerlink" href="#http" title="Permalink to this headline">¶</a></h2>
<p>You want to serve your custom javascript files on the network? Maybe you wanna inject some custom script or image into HTTP responses using a <a class="reference external" href="/proxying.html">transparent proxy module</a> but you got no public server to use? <strong>no worries dude</strong> :DA builtin HTTP server comes with bettercap, allowing you to serve custom contents from your own machine without installing and configuring other softwares such as Apache, nginx or lighttpd.</p>
<hr/><div class="section" id="httpd">
<span id="httpd"></span><h3><code class="docutils literal"><span class="pre">--httpd</span></code><a class="headerlink" href="#httpd" title="Permalink to this headline">¶</a></h3>
<p>Enable HTTP server, default to <code class="docutils literal"><span class="pre">false</span></code>.</p>
</div>
<div class="section" id="httpd-port-port">
<span id="httpd-port-port"></span><h3><code class="docutils literal"><span class="pre">--httpd-port</span> <span class="pre">PORT</span></code><a class="headerlink" href="#httpd-port-port" title="Permalink to this headline">¶</a></h3>
<p>Set HTTP server port, default to <code class="docutils literal"><span class="pre">8081</span></code>.</p>
</div>
<div class="section" id="httpd-path-path">
<span id="httpd-path-path"></span><h3><code class="docutils literal"><span class="pre">--httpd-path</span> <span class="pre">PATH</span></code><a class="headerlink" href="#httpd-path-path" title="Permalink to this headline">¶</a></h3>
<p>Set HTTP server path, default to <code class="docutils literal"><span class="pre">./</span></code>.</p>
</div>
</div>
<span id="document-servers/dns"></span><div class="section" id="dns">
<span id="dns"></span><h2>DNS<a class="headerlink" href="#dns" title="Permalink to this headline">¶</a></h2>
<p>If you want to perform DNS <a class="reference external" href="/docs/spoofing.html">spoofing</a>, you must specify the <code class="docutils literal"><span class="pre">--dns</span> <span class="pre">FILE</span></code> command line argument, where the <code class="docutils literal"><span class="pre">FILE</span></code> value is the name of a file composed by entries like the following:</p>
<script src="https://gist.github.com/evilsocket/2bea18a6db6af7deeb6c.js"></script><p>Then all you've left to do is execute:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">sudo</span> <span class="n">bettercap</span> <span class="o">--</span><span class="n">dns</span> <span class="n">dns</span><span class="o">.</span><span class="n">conf</span>
</pre></div>
</div>
<hr/><div class="section" id="dns-file">
<span id="dns-file"></span><h3><code class="docutils literal"><span class="pre">--dns</span> <span class="pre">FILE</span></code><a class="headerlink" href="#dns-file" title="Permalink to this headline">¶</a></h3>
<p>Enable DNS server and use this file as a hosts resolution table.</p>
</div>
<div class="section" id="dns-port-port">
<span id="dns-port-port"></span><h3><code class="docutils literal"><span class="pre">--dns-port</span> <span class="pre">PORT</span></code><a class="headerlink" href="#dns-port-port" title="Permalink to this headline">¶</a></h3>
<p>Set DNS server port, default to <code class="docutils literal"><span class="pre">5300</span></code>.</p>
</div>
</div>
</div>
</div>


           </div>
           <div class="articleComments">
            
           </div>
          </div>
          <footer>
  

  <hr/>

  <div role="contentinfo">
    <p>
        &copy; Copyright 2016, Simone &#39;evilsocket&#39; Margaritelli.

    </p>
  </div> 

</footer>

        </div>
      </div>

    </section>

  </div>
  


  

    <script type="text/javascript">
        var DOCUMENTATION_OPTIONS = {
            URL_ROOT:'./',
            VERSION:'stable',
            COLLAPSE_INDEX:false,
            FILE_SUFFIX:'.html',
            HAS_SOURCE:  true,
            SOURCELINK_SUFFIX: '.txt'
        };
    </script>
      <script type="text/javascript" src="/legacy/assets/jquery.js"></script>
      <script type="text/javascript" src="/legacy/assets/underscore.js"></script>
      <script type="text/javascript" src="/legacy/assets/doctools.js"></script>

  

  
  
    <script type="text/javascript" src="/legacy/assets/js/theme.js"></script>
  

  
  
  <script type="text/javascript">
      jQuery(function () {
          SphinxRtdTheme.StickyNav.enable();
      });
  </script>
  
 
<script type="text/javascript">
var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
</script>
<script type="text/javascript">
try {
var pageTracker = _gat._getTracker("UA-65617603-1");
pageTracker._trackPageview();
} catch(err) {}</script>


</body>
</html>
